OTP Validation API

Content

• Overview
• Requirements
• API Request
• Code Snippets
• Errors Codes and Responses

Overview

This api allow user to verify MSISDN ondemand without subscribing the applicaiton.

Flow is Send Verify Request -> Submit PIN

Introduction

OTP validation API API performs real-time checks to verify that the user possessed the device that carries the indicated mobile phone number. It provides a frequent method of verifying possession of the device by delivering an OTP (one-time password) through SMS and validating it afterwards.

SMS OTP (one time password) is a secure method for providing one-time access to an application or performing a single transaction. OTP is most effective and legitimate for a single transaction, unlike user-generated passwords. It is a secure authentication method where a text containing a unique alphanumeric or numeric code is sent to a mobile number (MSISDN).

The recipient then uses this code or password as an additional layer of security to login to a service, website or app.

Quick Start

The usage of the API is based on several resources.

Before starting to use the API, the developer needs to know about the below specified details:

API service endpoint

Two endpoints are defined in One Time Password SMS API:

• POST /apicall/openapi/one-time-password-sms/v1/send-code : Sends an SMS with the desired message and an OTP code to the received phone number
• POST /apicall/openapi/one-time-password-sms/v1/validate-code : Verifies the received code as input is valid for the given authenticationId.

Requirements

Authorization API calls
All API call request to ideabiz.lk required Authorization headers. Please refer the Token Management (http://docs.ideabiz.lk/Getting_Started/Token_Manegment) document for Authorization.

Request Header

Content-Type: application/json 
Authorization: Bearer [access token] 
Accept: application/json
x-correlator:ABC

Sample Request Header

Content-Type: application/json 
Authorization: Bearer a92ba8hjgjhgjh3fa1609cabcd79
x-correlator:ABC

API Request

Verification Request

URL

https://ideabiz.lk/apicall/openapi/one-time-password-sms/v1/send-code

Method

POST

Request

{
    "phoneNumber":"+9477xxxxxxx",
    "message":"{{code}} is your short code to authenticate with ABC App via SMS"
}

Response

{
    "authenticationId": "4eaa9cd7a59f4715b15bc33b79cbdcd7"
}

Submit PIN Request

URL

https://ideabiz.lk/apicall/openapi/one-time-password-sms/v1/validate-code

Method

POST

Request

{
  "code": "520972",
  "authenticationId": "4eaa9cd7a59f4715b15bc33b79cbdcd7"
}

Success Response

{
    "statusCode": "SUCCESS",
    "message": "Verification Status",
    "data": {
        "status": "SUCCESS",
        "authenticationId": "4eaa9cd7a59f4715b15bc33b79cbdcd7"
    }
}

Sample Error Response

{
  "statusCode": "ERROR",
  "message": "Wrong PIN",
  "data": null
}

{
  "statusCode": "ERROR",
  "message": "Max attempt exceeded",
  "data": null
}

Code Snippets

cURL Request - Validate Code

curl --location 'https://ideabiz.lk/apicall/openapi/one-time-password-sms/v1/validate-code' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer 4cf15b2f-6120-3c73-a492-a36da2e28d15' \
--data '{
    "msisdn":"9477xxxxxxx",
    "message":"Hi this is ABC Service, your code is {{code}}"
}'

cURL Request - Submit Code

curl --location 'https://ideabiz.lk/apicall/openapi/one-time-password-sms/v1/validate-code' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer 4cf15b2f-6120-3c73-a492-a36da2e28d15' \
--data '{
  "code": "684479",
  "authenticationId": "76d9c3235cd84b8a9bf4389f1d0f2989"
}'

Errors Codes and Responses

Since OTP validation API is based on REST design principles and blueprints, well defined HTTP status codes and families specified by community are followed.

Following table provides an overview of common error names, codes, and messages applicable to One Time Password SMS API.